
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Build a Renderer &#8212; PixieDust Documentation</title>
    <link rel="stylesheet" href="_static/better.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/custom.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '1.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="shortcut icon" href="_static/pd_icon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Test" href="test.html" />
    <link rel="prev" title="Write a new PixieDust Visualization" href="writeviz.html" />
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
  </head>
  <body>
    <header id="pageheader"><h1><a href="index.html ">
        PixieDust Documentation
    </a></h1></header>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="build-a-renderer">
<h1>Build a Renderer<a class="headerlink" href="#build-a-renderer" title="Permalink to this headline">¶</a></h1>
<p>A <em>rendering engine</em> turns your data into shapes and lines. PixieDust comes with a few built-in renderers like: matplotlib, Seaborn, Bokeh, Mapbox, and Google Maps. To switch between renderers, go to the upper right of your chart and click the <strong>Renderer</strong> dropdown:</p>
<img alt="_images/renderer_dd.png" src="_images/renderer_dd.png" />
<p>Choices available on this list depends upon what display option you choose. For example, Mapbox and Google Maps are available only for maps.</p>
<p>You can use all these renderers right away without much extra effort. But what if your favorite rendering engine is missing?</p>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>Adding a renderer is similar to <a class="reference external" href="writeviz.html">adding a display visualization</a>. (Though it’s actually simpler since you don’t have to build the metadata, which is replaced by defining the chartID your renderer is for.) Renderers use the same apis as visualizations, but you need to define a few extra things:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">rendererId</span></code> (must be unique to this renderer)  use <code class="docutils literal"><span class="pre">&#64;PixiedustRenderer</span></code> annotation</li>
<li>specify which charts the renderer can display, like <strong>map</strong> for example. List using same <code class="docutils literal"><span class="pre">&#64;PixiedustRenderer</span></code> annotation</li>
<li>inherit from specialized class <code class="docutils literal"><span class="pre">BaseChartDisplay</span></code>.</li>
<li>(optional) create a set of dynamic options using the <code class="docutils literal"><span class="pre">&#64;commonChartOptions</span></code> annotation</li>
<li>(optional) as necessary, override method(s) from BaseChartDisplay to control rendering. For example: <code class="docutils literal"><span class="pre">getNumFigures</span></code>, <code class="docutils literal"><span class="pre">getExtraFields</span></code>, and so on.</li>
<li>implement <code class="docutils literal"><span class="pre">doRenderChart</span></code> method</li>
</ul>
<p>We’ll soon post detailed instructions on how to implement this all manually, but there’s no need to wait! Read on to learn how to add a sample renderer and start exploring the code.</p>
</div>
<div class="section" id="add-a-renderer">
<h2>Add a Renderer<a class="headerlink" href="#add-a-renderer" title="Permalink to this headline">¶</a></h2>
<p>Since no documentation is as good the code itself, we created a little tool to help you generate bootstrap project that generates boilerplate code that you can then study to understand how it all fits together.</p>
<ol class="arabic simple">
<li>In Terminal or other command-line shell, navigate to the directory where you want to create the new project. This can be anywhere you choose.</li>
<li>Enter and run:</li>
</ol>
<blockquote>
<div><code class="docutils literal"><span class="pre">jupyter</span> <span class="pre">pixiedust</span> <span class="pre">generate</span></code></div></blockquote>
<ol class="arabic" start="3">
<li><p class="first">Respond to the questions/prompts to complete setup. Here’s the entire exchange including the command you’ll run in Step 4:</p>
<img alt="_images/generate.png" src="_images/generate.png" />
</li>
<li><p class="first">Install your new renderer.</p>
<p>If you’re not already there, cd into your project directory and run the following command:</p>
<p><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-e</span> <span class="pre">.</span></code></p>
</li>
<li><p class="first">Go to your notebook, and restart the kernel.</p>
</li>
<li><p class="first">Run the command <code class="docutils literal"><span class="pre">import</span> <span class="pre">pixiedust</span></code></p>
</li>
<li><p class="first">Run the command <code class="docutils literal"><span class="pre">import</span> <span class="pre">Sample</span></code>  (or whatever you named your project)</p>
</li>
<li><p class="first">Then load some data and run the display() command on it.</p>
</li>
<li><p class="first">In the charts dropdown, choose a chart you specified that the renderer can display.</p>
</li>
<li><p class="first">Click the <strong>Renderer</strong> dropdown.</p>
</li>
</ol>
<blockquote>
<div><p>You see your new renderer! Here’s one named <strong>Sample</strong>:</p>
<img alt="_images/sample_renderer.png" src="_images/sample_renderer.png" />
</div></blockquote>
<p>Explore the code in your new project directory. We’ve commented in some guidance that should help you understand what you’re looking at.</p>
</div>
<div class="section" id="more-to-come">
<h2>More to come<a class="headerlink" href="#more-to-come" title="Permalink to this headline">¶</a></h2>
<p>Watch this space for more details on coding your own renderer.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="use.html">Use PixieDust</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="develop.html">Develop for PixieDust</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="contribute.html">Contribute</a></li>
<li class="toctree-l2"><a class="reference internal" href="writeviz.html">Write a new PixieDust Visualization</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Build a Renderer</a></li>
<li class="toctree-l2"><a class="reference internal" href="test.html">Test</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="pixieapps.html">PixieApps</a></li>
<li class="toctree-l1"><a class="reference internal" href="pixiegateway.html">PixieGateway</a></li>
<li class="toctree-l1"><a class="reference internal" href="releasenotes.html">Release Notes</a></li>
</ul>

<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  <footer id="pagefooter">&copy; 2017, IBM.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a>
      1.6.3.

  </footer>

  
  </body>
</html>